home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 19 / CU Amiga Magazine's Super CD-ROM 19 (1998)(EMAP Images)(GB)[!][issue 1998-02].iso / CUCD / Online / RFCs / rfc / rfc0643.txt < prev    next >
Text File  |  1994-01-21  |  13KB  |  398 lines
  1.  
  2.  
  3.  
  4. Network Debugging Protocol                          Eric Mader
  5. RFC: 643                                             July 1974
  6. NIC #30873
  7.  
  8.  
  9.      This document describes a proposed protocol  to  be  used  in  an
  10. implementation   of   a   PDP-11   network  Bootstrap  service  and  a
  11. cross-network  debugger.   The  protocol  is  designed  for  debugging
  12. processes  running under an operating system which can perform some of
  13. the "lower level" debugging  tasks,  such  as  planting  and  removing
  14. breakpoints  and  single  stepping.  A subset of the protocol could be
  15. used if such a capability does not exist (a  stand-alone  program  for
  16. example).
  17.  
  18.      The protocol is a level 2 protocol, which  bypasses  the  ARPANET
  19. HOST-HOST  protocol.   (This  is  implemented  on  TENEX using special
  20. privileged system calls which allow messages to be  sent  directly  to
  21. and  received  directly  from the IMP).  Messages are sent between the
  22. PDP-11 and the remote debugger on  one  link  (currently  377  octal).
  23. Each  message from the remote debugger to the PDP-ll is a request that
  24. the PDP-11 perform some action, and each message from  the  PDP-11  to
  25. the remote debugger is either a reply to that request or an indication
  26. that  a  process  has  stopped  running  (i.e.   has  trapped,  hit  a
  27. breakpoint, etc).  The exact format of the messages is shown in Figure
  28. 1 below.
  29.  
  30.      Each  command  consists  of  an  8-bit  op-code,  and  an   8-bit
  31. process-id,  two  16-bit  arguments,  and  an optional string of 8-bit
  32. bytes.  The op-code field from the PDP-11 should be the same  as  that
  33. sent  by  the  remote  host  to  indicate successful completion of the
  34. request or be the same as that set by the remote host with the 200 bit
  35. set  to  indicate  failure to complete the request.  Op-codes from the
  36. PDP-11 which have the 100 bit set are asynchronous indication  that  a
  37. process  has stopped for a reason other than a request from the remote
  38. host.  (See description of asynchronous replies  below).   An  op-code
  39. from  the  PDP-11  with  both  the 100 and 200 bit set is meaningless.
  40. Thus, the 8-bit op-code field sent by the PDP-11 can be thought of  as
  41. a CAN'T Flag, an Asynchronous STOP Flag, and a 6-bit op-code.
  42.  
  43.      In the description that follows the commands will be given as
  44.  
  45.    NAME (Process-ID, Argument 1, Argument 2, BYTE STRING)
  46. with only as many of the fields present as are used.
  47.  
  48. Op-Code 0 - NOP
  49. _______ _ _ ___
  50.  
  51.      This command is intended to be used to determine if the PDP-11 is
  52. operational.   It  has no effect on any process running in the PDP-11.
  53. The response is NOP.
  54.  
  55. Op-Code 1 - DEBUG (Process)
  56. _______ _ _ _____ _________
  57.  
  58.      This command requests the ability to  debug  the  given  process.
  59. The PDP-11 should respond with
  60.  
  61.                                                     Page   2
  62.  
  63.  
  64.  
  65.                      DEBUGGING (process)
  66.  
  67. (op-code 1) if no other remote host is currently doing so, and
  68.  
  69.                     CAN'T DEBUG (process)
  70.  
  71. (op-code 201) if another remote host  has  been  given  permission  to
  72. debug the process, or the process doesn't exist.
  73.  
  74. Op-Code 2 - END DEBUG (Process)
  75. _______ _ _ ___ _____ _________
  76.  
  77.      This command relinquishes the ability to debug  a  process.   The
  78. PDP-11 should reply
  79.  
  80.                      END DEBUG (Process)
  81.  
  82. (op-code 2) unless the remote host isn't  debugging  the  process,  in
  83. which case it should respond 
  84.  
  85.                   CAN'T END DEBUG (Process)
  86.  
  87. (op-code 202).  If the process isn't running when  the  END  DEBUG  is
  88. done, then the effect should be the same as
  89.  
  90.                       RESUME (PROCESS)
  91.                     END DEBUG (PROCESS)
  92.  
  93. Op-Code 3 - STOP (Process)
  94. _______ _ _ ____ _________
  95.  
  96.      This command requests the PDP-11 to stop the given  process  from
  97. running.  The PDP-11 should respond
  98.  
  99.                       STOPPED (process)
  100.  
  101. (op-code 3) unless the process isn't  being  debugged  by  the  remote
  102. host.  In this case it should reply
  103.  
  104.                     CAN'T STOP (process)
  105.  
  106.   (op-code 203).
  107.  
  108. Op-Code 4 - DEPOSIT (Process, Address, Count, Byte String)
  109. _______ _ _ _______ _________ ________ ______ ____ _______
  110.  
  111.      This instructs the PDP-11 to deposit  the  Count  bytes  in  Byte
  112. String  into  the  given process's address space beginning at Address.
  113. The PDP-11 should reply
  114.  
  115.              DEPOSITED (Process, Address, Count)
  116.  
  117. if successful or
  118.  
  119.            CAN'T DEPOSIT (Process, Address, Count)
  120.  
  121.                                                     Page   3
  122.  
  123.  
  124.  
  125. if the deposit doesn't succeed, or the remote host isn't debugging the
  126. process.
  127.  
  128. Op-Code 5 - RESUME (Process)
  129. _______ _ _ ______ _________
  130.  
  131.      This instructs the PDP-11 to allow the given  process  to  resume
  132. running.  The PDP-11 should reply
  133.  
  134.                      RESUMED (Process)
  135.  
  136. before it starts the process (in case it traps right away), or
  137.  
  138.                    CAN'T RESUME (Process)
  139.  
  140. if the process wasn't stopped, or the remote host isn't debugging  the
  141. process.
  142.  
  143. Op-Code 6 - EXAMINE (Process, Address, Count)
  144. _______ _ _ _______ _________ ________ ______
  145.  
  146.      This instructs the PDP-11 to return Count bytes  from  the  given
  147. process address space starting at Address.  The PDP-11 should reply
  148.  
  149.        CONTENTS (Process, Address, Count, Byte String)
  150.  
  151. if it can supply the bytes, or
  152.  
  153.            CAN'T EXAMINE (Process, Address, Count)
  154.  
  155. if all the bytes don't exist in the address space, or the remote  host
  156. isn't debugging the process.
  157.  
  158. Op-Code 7 - DEPOSIT STATE VECTOR (Process, Index, Byte Count,
  159. _______ _ _ _______ _____ ______ _________ ______ ____ ______
  160.             Byte String)
  161.             ____ _______
  162.  
  163.      This instructs the PDP-11 to deposit the Byte Count bytes in Byte
  164. String  into the state vector for the given process starting with byte
  165. Index.  See Figure 2 for the format of the state vector.   The  PDP-11
  166. should reply
  167.  
  168.      DEPOSITED STATE VECTOR (Process, Index, Byte Count)
  169.  
  170. unless the bytes won't all fit in the state vector or the remote  host
  171. isn't debugging the process.  In this case the reply should be
  172.  
  173.   CAN'T DEPOSIT STATE VECTOR (Process, Index, Byte Count)
  174.  
  175. Op-Code 10 - BREAK (Process, Address, Proceed Count)
  176. _______ __ _ _____ _________ ________ _______ ______
  177.  
  178.      This instructs the PDP-11 to place a breakpoint at Address in the
  179. given  process's address space, with a proceed count of Proceed Count.
  180. The proceed count can be changed by issuing another BREAK with a
  181. different count.  The PDP-11 should reply
  182.  
  183.                                                     Page   4
  184.  
  185.  
  186.  
  187.            BROKE (Process, Address, Proceed Count)
  188.  
  189. if it was able to plant the breakpoint and
  190.  
  191.         CAN'T BREAK (Proceed, Address, Proceed Count)
  192.  
  193. if it was unable to plant the breakpoint because the breakpoint tables
  194. for  the  process are full, or because the remote host isn't debugging
  195. the process.  Note that the  PDP-11  must  keep  track  of  where  the
  196. breakpoints are, the old contents of these locations etc.
  197.  
  198. Op-Code 11 - UNBREAK (Process, Address)
  199. _______ __ _ _______ _________ ________
  200.  
  201.      This instructs the PDP-11 to remove the breakpoint  from  Address
  202. in the process's address space and release all storage associated with
  203. it.  The PDP-11 should reply
  204.  
  205.                  UNBROKE (Process, Address)
  206.  
  207. when the breakpoint is removed, or
  208.  
  209.               CAN'T UNBREAK (Process, Address)
  210.  
  211. if the process doens't have a breakpoint at Address or the remote host
  212. isn't debugging the process.
  213.  
  214. Op-Code 12 - SINGLE STEP (Process)
  215. _______ __ _ ______ ____ _________
  216.  
  217.      This instructs the PDP-11 to let the given  process  execute  one
  218. instruction, using the Trace Trap feature.  The PDP-11 should reply
  219.  
  220.                   SINGLE STEPPING (Process)
  221.  
  222. before the process is started, or
  223.  
  224.                  CAN'T SINGLE STEP (Process)
  225.  
  226. if the process is already running or the remote host  isn't  debugging
  227. the process.
  228.  
  229. Op-Code 13 - PROCEED BPT (Process)
  230. _______ __ _ _______ ___ _________
  231.  
  232.      This instructs the PDP-11 to allow the process to proceed from  a
  233. break point trap (BPT, see below).  The PDP-11 should reply
  234.  
  235.                   PROCEEDING BPT (Process)
  236.  
  237. before allowing the process to proceed, or
  238.  
  239.                  CAN'T PROCEED BPT (Process)
  240.  
  241. if the process isn't stopped at a breakpoint or the remote host  isn't
  242. debugging the process.
  243.  
  244.                                                     Page   5
  245.  
  246.  
  247.  
  248. Op-Code 14 - CREATE PROCESS
  249. _______ __ _ ______ _______
  250.  
  251.      This instructs the PDP-11 to  create  a  process  (with  its  own
  252. virtual address space if the system will support such a feature).  The
  253. PDP-11 should reply
  254.  
  255.                   CREATED PROCESS (Process)
  256.  
  257. if it could create a process, with the process-id in process.  If  the
  258. process  creation  failed  or  the system cannot create processes, the
  259. PDP-11 should reply
  260.  
  261.                     CAN'T CREATE PROCESS.
  262.  
  263. Once a remote host has created a process it is debugging it, that is a
  264.  
  265.                        DEBUG (process)
  266.  
  267. need not be done.
  268.  
  269. Op-Code 15 - DESTROY PROCESS (Process)
  270. _______ __ _ _______ _______ _________
  271.  
  272.      This instructs the PDP-11 to destroy the  given  process.   After
  273. the  process  is destroyed the remote host cannot, of course, debug it
  274. so there is no need to do an
  275.  
  276.                     END DEBUG (Process).
  277.  
  278. The PDP-11 should reply
  279.  
  280.                  DESTROYED PROCESS (Process)
  281.  
  282. if the process has been destroyed.  If the system  doesn't  support  a
  283. multi-process structure or the remote host isn't debugging the process
  284. the PDP-11 should reply
  285.  
  286.               CAN'T DESTROY PROCESS (Process).
  287.  
  288.  
  289.  
  290.  
  291.                  Asynchronous Stop Replies
  292.                  ____________ ____ _______
  293.  
  294.      These replies (op-code between 100 and 177 octal) are sent by the
  295. PDP-11  wherever a process being debugged stops running for any reason
  296. other than in response to the
  297.  
  298.                        STOP (Process)
  299.  
  300. command.  Each of these replies includes the entire state  vector  for
  301. the process.
  302.  
  303.                                                     Page   6
  304.  
  305.  
  306.  
  307. Op-Code 100 - TRAP (Process, Reason, 0, STATE VECTOR)
  308. _______ ___ _ ____ _________ _______ __ _____ _______
  309.  
  310.      This informs the remote host that a  process  has  "trapped",  or
  311. terminated abnormally.  The reason is a system error code, or could be
  312. a trap vector address in the stand-alone case.
  313.  
  314. Op-Code 101 - HALT (Process, 0,0, STATE VECTOR)
  315. _______ ___ _ ____ _________ ____ _____ _______
  316.  
  317.      This  informs  the  remote  host  that  the  given  process   has
  318. terminated normally. 
  319.  
  320. Op-Code 102 - BPT (Process, 0, 0, STATE VECTOR)
  321. _______ ___ _ ___ _________ __ __ _____ _______
  322.  
  323.      This informs the remote host that the given  process  has  hit  a
  324. breakpoint trap.
  325.  
  326. Op-Code 103 - TTRAP (Process, 0, 0, STATE VECTOR)
  327. _______ ___ _ _____ _________ __ __ _____ _______
  328.  
  329.      This informs the remote host that the given  process  has  hit  a
  330. trace trap, i.e.  has just executed one instruction in response to the
  331.  
  332.                     SINGLE STEP (Process)
  333.  
  334. command.
  335.  
  336.                                                     Page   7
  337.  
  338.  
  339.                           Figure 1
  340.  
  341.              FORMAT OF NETWORK DEBUGGER MESSAGES
  342.  
  343.  
  344.                     ----------------
  345.                    | TYPE | HOST    |
  346.                     ----------------
  347.                    | LINK | STYPE   |
  348.                     ----------------
  349.                    | CMD  |  PID    |
  350.                     ----------------
  351.                    |    ARG1        |
  352.                     ----------------
  353.                    |    ARG2        |
  354.                     ----------------
  355.  
  356.      TYPE -- The HOST-IMP/IMP-HOST message type, should
  357.              always be zero.
  358.  
  359.      HOST -- The source host ID.
  360.  
  361.      LINK -- The debugger link.
  362.  
  363.     STYPE -- The message subtype, always zero.
  364.  
  365.       CMD -- The debugger command op-code, excess 100 for
  366.              asynchronous reply's, excess 200 for "can't"
  367.              reply's.
  368.  
  369.       PID -- Process ID of process being debugged.
  370.  
  371.      ARG1 -- The first argument of the command.
  372.  
  373.      ARG2 -- The second argument of the command.
  374.  
  375.  
  376.                                                  Page 8
  377.  
  378.  
  379.  
  380.  
  381.                           Figure 2
  382.  
  383.                   FORMAT OF STATE VECTORS
  384.  
  385.                       ------------
  386.                      |    R0      |
  387.                       ------------
  388.                      |    R1      |
  389.                       ------------
  390.                      |    R2      |
  391.                       ------------
  392.                      |   ...      |
  393.                       ------------
  394.                      |    PC      |
  395.                       ------------
  396.                      |    PS      |
  397.                       ------------
  398.